The default folder structure centers around an 'app' directory with file-based routing, where folders define routes and special files define the UI behavior
Next.js 13 introduced the App Router as a new approach to building applications, built on React Server Components. Unlike the previous Pages Router, the App Router uses a file-system based router where the structure of folders and files inside the 'app' directory directly defines your application's routes and behavior. This convention-over-configuration approach eliminates the need for manual route setup and provides built-in support for layouts, loading states, error handling, and more .
layout.tsx: Defines shared UI that wraps around page content. The root layout (app/layout.tsx) is required and must contain <html> and <body> tags. Layouts are not re-rendered during navigation, making them efficient for persistent elements like headers and footers .
page.tsx: Represents the unique UI for a route. Every route segment that should be publicly accessible must contain a page.tsx file. These are Server Components by default but can be marked as Client Components with 'use client' .
loading.tsx: Creates a loading UI (automatically wrapped in a Suspense boundary) that displays while the page content is loading. This improves perceived performance by showing immediate feedback .
error.tsx: Defines a custom error UI that catches errors in the route segment. Must be a Client Component (use 'use client') and receives 'error' and 'reset' props .
not-found.tsx: Displays a custom 404 page when a route is not found or when the notFound() function is called .
route.ts: Creates custom API endpoints (replacing pages/api in the Pages Router). Allows handling different HTTP methods (GET, POST, etc.) .
template.tsx: Similar to layout.tsx but creates a new instance on each navigation, useful for animations or state that should reset between routes .
global-error.tsx: A fallback error UI that wraps the entire application. Only used in production and must include its own <html> and <body> tags .
Route groups, created by wrapping folder names in parentheses like (marketing), allow you to organize routes logically without affecting the URL structure. This is particularly useful for separating sections like marketing pages, authentication flows, or admin areas while maintaining clean URLs like /about and /login instead of /marketing/about or /auth/login . Additionally, you can use private folders by prefixing folder names with an underscore (e.g., _components) to indicate they are for internal organization and should not be treated as routes .
Dynamic routes are created using square brackets in folder names, such as [slug] or [id]. This captures URL parameters that can be accessed in your page component via the params prop. For catch-all routes, you can use [...slug] to match multiple path segments, or [[...slug]] for optional catch-all routes. These patterns enable flexible content structures like blog posts, product pages, or any parameterized content .
public/: Stores static assets like images, fonts, and files that need to be publicly accessible. Files here are served at the root URL (e.g., /images/logo.png) .
src/: An optional directory for source code. If used, the app directory should be placed inside src/app/ .
middleware.ts: Located at the project root, this file allows you to run code before requests complete, useful for authentication, redirects, and rewriting URLs .
api/: A convention for API routes within the app directory, with route.ts files handling server-side logic for endpoints like /api/hello .